<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
                      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
    <meta http-equiv="content-type" content="text/html; charset=UTF-8"/>
    <title>Plural notations for Translation - Zend Framework Manual</title>

    <link href="../css/shCore.css" rel="stylesheet" type="text/css" />
    <link href="../css/shThemeDefault.css" rel="stylesheet" type="text/css" />
    <link href="../css/styles.css" media="all" rel="stylesheet" type="text/css" />
</head>
<body>
<h1>Zend Framework</h1>
<h2>Programmer's Reference Guide</h2>
<ul>
    <li><a href="../en/zend.translate.plurals.html">Inglês (English)</a></li>
    <li><a href="../pt-br/zend.translate.plurals.html">Português Brasileiro (Brazilian Portuguese)</a></li>
</ul>
<table width="100%">
    <tr valign="top">
        <td width="85%">
            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="zend.translate.additional.html">Additional features for translation</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="zend.translate.html">Zend_Translate</a></span><br />
                        <span class="home"><a href="manual.html">Programmer's Reference Guide</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="zend.uri.html">Zend_Uri</a></div>
                    </td>
                </tr>
            </table>
<hr />
<div id="zend.translate.plurals" class="section"><div class="info"><h1 class="title">Plural notations for Translation</h1></div>
    

    <p class="para">
        As of Zend Framework 1.9, <span class="classname">Zend_Translate</span> is able to provide plural
        support. Professional translation will always have the need to use plurals as they are
        native in almost all languages.
    </p>

    <p class="para">
        So what are plurals? Generally spoken plurals are words which take into account numeric
        meanings. But as you may imagine each language has it&#039;s own definition of plurals.
        English, for example, supports one plural. We have a singular definition, for example
        &quot;car&quot;, which means implicit one car, and we have the plural definition, &quot;cars&quot; which could
        mean more than one car but also zero cars. Other languages like Russian or Polish have
        more plurals and also the rules for plurals are different.
    </p>

    <p class="para">
        When you want to use plurals with <span class="classname">Zend_Translate</span> you must not need
        to know how the plurals are defined, only the translator must know as he does the
        translation. The only information you need to have is the language.
    </p>

    <p class="para">
        There are two ways for using plurals... the traditional one, which means that you use a own
        method, and a modern one, which allows you to do plural translations with the same method
        as normal translations.
    </p>

    <div class="section" id="zend.translate.plurals.traditional"><div class="info"><h1 class="title">Traditional plural translations</h1></div>
        

        <p class="para">
            People who worked with gettext in past will be more common with traditional plural
            translations. There is a own  <span class="methodname">plural()</span> method which can be
            used for plural translations.
        </p>

        <div class="example" id="zend.translate.plurals.traditional.example1"><div class="info"><p><b>Example #1 Example of traditional plural translations</b></p></div>
            

            <div class="example-contents"><p>
                The  <span class="methodname">plural()</span> method accepts 4 parameters. The first
                parameter is the singular messageId, the second is the plural messageId and the
                third is the number or amount.
            </p></div>

            <div class="example-contents"><p>
                The number will be used to detect the plural which has to be returned. A optional
                fourth parameter can be used to give a locale which will be used to return the
                translation.
            </p></div>

            <pre class="programlisting brush: php">
$translate = new Zend_Translate(
    array(
        &#039;adapter&#039; =&gt; &#039;gettext&#039;,
        &#039;content&#039; =&gt; &#039;/path/to/german.mo&#039;,
        &#039;locale&#039;  =&gt; &#039;de&#039;
    )
);
$translate-&gt;plural(&#039;Car&#039;, &#039;Cars&#039;, $number);
</pre>

        </div>
    </div>

    <div class="section" id="zend.translate.plurals.modern"><div class="info"><h1 class="title">Modern plural translations</h1></div>
        

        <p class="para">
            As traditional plural translations are restricted to source code using English plurals
            we added a new way for plural translations. It allows to use the same
             <span class="methodname">translate()</span> for standard and for plural translations.
        </p>

        <p class="para">
            To use plural translations with  <span class="methodname">translate()</span> you need to give
            an array as messageId instead of an string. This array must have the original plural
            messageId&#039;s, then the amount and at last an optional locale when your given messageId&#039;s
            are not in English notation.
        </p>

        <div class="example" id="zend.translate.plurals.modern.example1"><div class="info"><p><b>Example #2 Example of modern plural translations</b></p></div>
            

            <div class="example-contents"><p>
                When we want to translate the same plural definitions like in the previous our
                example would have to be defined like below.
            </p></div>

            <pre class="programlisting brush: php">
$translate = new Zend_Translate(
    array(
        &#039;adapter&#039; =&gt; &#039;gettext&#039;,
        &#039;content&#039; =&gt; &#039;/path/to/german.mo&#039;,
        &#039;locale&#039;  =&gt; &#039;de&#039;
    )
);
$translate-&gt;translate(array(&#039;Car&#039;, &#039;Cars&#039;, $number));
</pre>

        </div>

        <p class="para">
            Using modern plural translations it is also possible to use any language as source
            for messageId&#039;s.
        </p>

        <div class="example" id="zend.translate.plurals.modern.example2"><div class="info"><p><b>Example #3 Example of modern plural translations using a different source language</b></p></div>
            

            <div class="example-contents"><p>
                Let&#039;s expect we want to use Russian and let&#039;s also expect that the given
                messageId&#039;s are Russian and not English.
            </p></div>

            <pre class="programlisting brush: php">
$translate = new Zend_Translate(
    array(
        &#039;adapter&#039; =&gt; &#039;gettext&#039;,
        &#039;content&#039; =&gt; &#039;/path/to/german.mo&#039;,
        &#039;locale&#039;  =&gt; &#039;de&#039;
    )
);
$translate-&gt;translate(
    array(
        &#039;Car&#039;,
        &#039;Cars first plural&#039;,
        &#039;Cars second plural&#039;,
        $number,
        &#039;ru&#039;
    )
);
</pre>

        </div>

        <p class="para">
            As you can see you can give more than just the one English plural. But you must give
            the source language in this case so <span class="classname">Zend_Translate</span> knows which
            plural rules it has to apply.
        </p>

        <p class="para">
            When you omit the plural language then English will be used per default and any
            additional plural definition will be ignored.
        </p>
    </div>

    <div class="section" id="zend.translate.plurals.source"><div class="info"><h1 class="title">Plural source files</h1></div>
        

        <p class="para">
            Not all source formats support plural forms. Look into this list for details:
        </p>

        <table id="zend.translate.plurals.source.supportedadapters" class="doctable table"><div class="info"><caption><b>Plural support</b></caption></div>
            

            
                <thead valign="middle">
                    <tr valign="middle">
                        <th>Adapter</th>
                        <th>Plurals supported</th>
                    </tr>

                </thead>


                <tbody valign="middle" class="tbody">
                    <tr valign="middle">
                        <td align="left">Array</td>
                        <td align="left"><em class="emphasis">yes</em></td>
                    </tr>


                    <tr valign="middle">
                        <td align="left">Csv</td>
                        <td align="left"><em class="emphasis">yes</em></td>
                    </tr>


                    <tr valign="middle">
                        <td align="left">Gettext</td>
                        <td align="left"><em class="emphasis">yes</em></td>
                    </tr>


                    <tr valign="middle">
                        <td align="left">Ini</td>
                        <td align="left"><em class="emphasis">no</em></td>
                    </tr>


                    <tr valign="middle">
                        <td align="left">Qt</td>
                        <td align="left"><em class="emphasis">no</em></td>
                    </tr>


                    <tr valign="middle">
                        <td align="left">Tbx</td>
                        <td align="left"><em class="emphasis">no</em></td>
                    </tr>


                    <tr valign="middle">
                        <td align="left">Tmx</td>
                        <td align="left"><em class="emphasis">no</em></td>
                    </tr>


                    <tr valign="middle">
                        <td align="left">Xliff</td>
                        <td align="left"><em class="emphasis">no</em></td>
                    </tr>


                    <tr valign="middle">
                        <td align="left">XmlTm</td>
                        <td align="left"><em class="emphasis">no</em></td>
                    </tr>

                </tbody>
            
        </table>


        <p class="para">
            Below you can find examples of plural defined source files.
        </p>

        <div class="section" id="zend.translate.plurals.source.array"><div class="info"><h1 class="title">Array source with plural definitions</h1></div>
            

            <p class="para">
                An array with plural definitions has to look like the following example.
            </p>

            <pre class="programlisting brush: php">
array(
    &#039;plural_0&#039; =&gt; array(
        &#039;plural_0 (ru)&#039;,
        &#039;plural_1 (ru)&#039;,
        &#039;plural_2 (ru)&#039;,
        &#039;plural_3 (ru)&#039;
    ),
    &#039;plural_1&#039; =&gt; &#039;&#039;
);
</pre>


            <p class="para">
                In the above example &#039;plural_0&#039; and &#039;plural_1&#039; are the
                plural definitions from the source code. And the array at &#039;plural_0&#039;
                has all translated plural forms available. Take a look at the following example
                with real content and translation from English source to German.
            </p>

            <pre class="programlisting brush: php">
array(
    &#039;Car&#039; =&gt; array(
        &#039;Auto&#039;,
        &#039;Autos&#039;
    ),
    &#039;Cars&#039; =&gt; &#039;&#039;
);
</pre>


            <p class="para">
                When your translated language supports more plural forms then simply add them to
                the array below the first plural form. When your source language supports more
                plural forms, than simply add a new empty translation.
            </p>
        </div>

        <div class="section" id="zend.translate.plurals.source.csv"><div class="info"><h1 class="title">Csv source with plural definitions</h1></div>
            

            <p class="para">
                A csv file with plural definitions has to look like the following example.
            </p>

            <pre class="programlisting brush: php">
&quot;plural_0&quot;;&quot;plural_0 (ru)&quot;;&quot;plural_1 (ru)&quot;;&quot;plural_2 (ru)&quot;;&quot;plural_3 (ru)&quot;
&quot;plural_1&quot;;
</pre>


            <p class="para">
                All translated plural forms have to be added after the first plural of the source
                language. And all further plural forms of the source language have to be added
                below but without translation. Note that you must add a delimiter to empty
                source plurals.
            </p>
        </div>

        <div class="section" id="zend.translate.plurals.source.gettext"><div class="info"><h1 class="title">Gettext source with plural definitions</h1></div>
            

            <p class="para">
                Gettext sources support plural forms out of the box. There is no need for adoption
                as the <var class="filename">*.mo</var> file will contain all necessary data.
            </p>

            <blockquote class="note"><p><b class="note">Note</b>: 
                <p class="para">
                    Note that gettext does not support the usage of source languages which are not
                    using english plural forms. When you plan to use a source language which
                    supports other plural forms like russian for example, then you can not use
                    gettext sources.
                </p>
            </p></blockquote>
        </div>
    </div>

    <div class="section" id="zend.translate.plurals.customrules"><div class="info"><h1 class="title">Custom plural rules</h1></div>
        

        <p class="para">
            In rare cases it could be useful to be able to define own plural rules. See Chinese for
            example. This language defines two plural rules. Per default it does not use plurals.
            But in rare cases it uses a rule like <em class="emphasis">(number == 1) ? 0 : 1</em>.
        </p>

        <p class="para">
            Also when you want to use a language which has no known plural rules, and would want to
            define your own rules.
        </p>

        <p class="para">
            This can be done by using  <span class="methodname">Zend_Translate_Plural::setRule()</span>.
            The method expects two parameters which must be given. A rule, which is simply a
            callback to a self defined method. And a locale for which the rule will be used.
        </p>

        <p class="para">
            Your rule could look like this:
        </p>

        <pre class="programlisting brush: php">
public function MyRule($number) {
    return ($number == 10) ? 0 : 1;
}
</pre>


        <p class="para">
            As you see, your rule must accept one parameter. It is the number which you will use to
            return which plural the translation has to use. In our example we defined that when we
            get a &#039;10&#039; the plural definition 0 has to be used, in all other cases we&#039;re using 1.
        </p>

        <p class="para">
            Your rules can be as simple or as complicated as you want. You must only return an
            integer value. The plural definition 0 stands for singular translation, and 1 stands for
            the first plural rule.
        </p>

        <p class="para">
            To activate your rule, and to link it to the wished locale, you have to call it like
            this:
        </p>

        <pre class="programlisting brush: php">
Zend_Translate_Plural::setPlural(&#039;MyPlural&#039;, &#039;zh&#039;);
</pre>


        <p class="para">
            Now we linked our plural definition to the Chinese language.
        </p>

        <p class="para">
            You can define one plural rule for every language. But you should be aware that you set
            the plural rules before you are doing translations.
        </p>

        <blockquote class="note"><p><b class="note">Note</b>: <span class="info"><b>Define custom plurals only when needed</b><br /></span>
            

            <p class="para">
                <span class="classname">Zend_Translate</span> defines plurals for most known languages.
                You should not define own plurals when you are not in need. The default rules work
                most of time.
            </p>
        </p></blockquote>
    </div>
</div>
        <hr />

            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="zend.translate.additional.html">Additional features for translation</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="zend.translate.html">Zend_Translate</a></span><br />
                        <span class="home"><a href="manual.html">Programmer's Reference Guide</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="zend.uri.html">Zend_Uri</a></div>
                    </td>
                </tr>
            </table>
</td>
        <td style="font-size: smaller;" width="15%"> <style type="text/css">
#leftbar {
	float: left;
	width: 186px;
	padding: 5px;
	font-size: smaller;
}
ul.toc {
	margin: 0px 5px 5px 5px;
	padding: 0px;
}
ul.toc li {
	font-size: 85%;
	margin: 1px 0 1px 1px;
	padding: 1px 0 1px 11px;
	list-style-type: none;
	background-repeat: no-repeat;
	background-position: center left;
}
ul.toc li.header {
	font-size: 115%;
	padding: 5px 0px 5px 11px;
	border-bottom: 1px solid #cccccc;
	margin-bottom: 5px;
}
ul.toc li.active {
	font-weight: bold;
}
ul.toc li a {
	text-decoration: none;
}
ul.toc li a:hover {
	text-decoration: underline;
}
</style>
 <ul class="toc">
  <li class="header home"><a href="manual.html">Programmer's Reference Guide</a></li>
  <li class="header up"><a href="manual.html">Programmer's Reference Guide</a></li>
  <li class="header up"><a href="reference.html">Zend Framework Reference</a></li>
  <li class="header up"><a href="zend.translate.html">Zend_Translate</a></li>
  <li><a href="zend.translate.introduction.html">Introduction</a></li>
  <li><a href="zend.translate.adapter.html">Adapters for Zend_Translate</a></li>
  <li><a href="zend.translate.using.html">Using Translation Adapters</a></li>
  <li><a href="zend.translate.sourcecreation.html">Creating source files</a></li>
  <li><a href="zend.translate.additional.html">Additional features for translation</a></li>
  <li class="active"><a href="zend.translate.plurals.html">Plural notations for Translation</a></li>
 </ul>
 </td>
    </tr>
</table>

<script type="text/javascript" src="../js/shCore.js"></script>
<script type="text/javascript" src="../js/shAutoloader.js"></script>
<script type="text/javascript" src="../js/main.js"></script>

</body>
</html>